% -*-LaTeX-*-
% Converted automatically from troff to LaTeX
% by tr2latex ($Revision: 2.2 $$Date: 1992/04/27 15:13:26 $ by C. Engel)
% on Tue Feb 08 12:43:59 1994
% tr2latex was written by Kamal Al-Yahya at Stanford University
% (Kamal%Hanauma@SU-SCORE.ARPA)
% and substantially enhanced by Christian Engel at RWTH Aachen
% (krischan@informatik.rwth-aachen.de).
%
% troff input file: widget.ms

\documentstyle[troffms]{article}
\begin{document}
%--------------------------------------------------
% start of input file: widget.ms
%
%.ND
\par\noindent
%.nr PS 12
%.nr VS 13
\par\noindent
%.nh
%.RP
\title{A Window based Interactive Programming Utility On Unix: \\
A Library Package for C programmers}
\author{Richard A. Culshaw}
\authoraff{GEC Hirst Research Centre \\
Data Systems Division \\
East Lane \\
Wembley \\
Middlesex HA9 7PP}
%.ND
{\nobreak
\shead{INTRODUCTION}

\par
A Widget is a user definable 
{\bf window\ gadget.}
 They allow the user to interact with the program in specifying operations to be carried out. Widgetlib is a set of library functions which allows the user to create and interact with 
{\bf widgets.}
A widget can be one of four types :
\par\noindent
      1) 
{\bf Command}
Widget 
      2) 
{\bf Label}
Widget
      3) 
{\bf Toggle}
Widget
      4) 
{\bf Input}
Widget

\shead{Command Widgets}
\par
A command widget allows the user to select a function to be carried out, e.g in a paging program one such command could be 'Next Page'. In creating a command widget the programmer must pass it the function to be carried out when the widget is selected (activated). The widget is activated using a unique 'activation' character which is displayed in the widget for easy reference.

\shead{Label Widgets}
\par
A label widget is simply a widget which holds a character string such as a heading, which can be changed at will later. The programmer can supply parameters which can either left justify (default), right justify, or centre the message within the widget (which has a user definable width) as well as highlight (default) or dehighlight it.

\shead{Toggle Widgets}
\par
A toggle widget contains a message which indicates the current value of an entity which can be more than one value e.g, Yes/No/Don't-Know. The value is toggled when a given character is pressed. The activation character is also displayed in the widget. At any point the programmer can enquire as to the the current toggle value.

\shead{Input Widgets}
\par
An input widget allows the user to enter information into the program in the form of a string, e.g in a paging program one might want to supply a file name. There are two types of input widgets :

a) The widget is activated immediately on creation therefore an activation character is not required. E.g in a paging program one might have a command widget which activates this type of input widget in order to get a file name.
\par\noindent
b) The widget has an associated activation character so therefore it may be activated at any point after creation. The character is displayed in the widget.

For ease of use the input widgets contain character strings which can explain
there use within the program.
}
\newpage
\shead{Text Window}
\par
The library also allows the user to define a text window into which the program may report information. On creation the program has to pass a parameter which specifies how much room to leave before the top of the text window. E.g 0 means place the window immediately below the lowest widget, 1 means allow room for one more row of widgets before placing the window. The text window always stretches to the bottom of the screen. The window can be bordered on any 2 opposite sides or on all 4 (effectively boxing 





it).

\shead{Widget Placement}
\par
The library maintains the current X,Y coordinate of the last widget created. When a new widget is created the program must pass a parameter 0 or 1. A 0 means put the new widget on the current row if possible, else go onto the next row. A 1 forces the new widget onto the next row. This means that widgets can only go after preceding ones and not before. But however widgets can be placed over widgets which have previously been destroyed.

\shead{Compiling Things}
\par
In order to use the library, it is necessary to have certain types and variables defined. Therefore, the program must have the line:
\par
{\bf \#include\ $<$widgets.h$>$}
\par\noindent
at the top of the source. The header file includes $<$curses.h$>$, $<$sgetty.h$>$, $<$stdio.h$>$ so you don't have to include them also. Also compilations should have the following form:
\par
{\bf cc\ [flags]\ file\ ...\ -lwidgets\ -lcurses}

\shead{Type Definitions}
\par\noindent
The functions which create widgets return a type 
{\bf WIDGET}
which is used for later identification of the widget.
\par\noindent
If a function is required to return a widget identifier, then it will return 
{\bf NULLWIDGET}
upon error.

\shead{Screen Refresh}
\par\noindent
The library supports a standard screen refresh invoked by \^{}L.

\newpage
{\nobreak
\shead{USAGE}
\shead{Getting Started}
\par\noindent
The first thing to do when using the library is set up the windowing system by calling 
\par\noindent
\ind{0.5in}
initialisewidgets()
\ind{0.0em}

\shead{Creating Widgets}
\par\noindent
\nwl

\ind{0.5in}
WIDGET mkcmdwidget (message, ch, function, row)
\nwl
char message[];
\nwl
char ch;
\nwl
int 
(*func)();
\nwl
int line;
\ind{0.0em}
\par\noindent
Creates a new command widget. message holds the message to be displayed in the command widget. ch is the activation character on which function is executed. row specifies where to place the widget (as described above). The returned value is the widget identifier for later use.

\par\noindent
\ind{0.5in}
WIDGET mklblwidget (message, position, space, row)
\nwl
char message[];
\nwl
int  position, space, row;
\ind{0.0em}
\par\noindent
Creates a new label widget. Message holds the contents of the label, position specifies how the message is to appear. Using the constants CENTRE, LEFTJUST, RIGHTJUST, NOHIGH, pass a combination to position e.g CENTRE or LEFTJUST$|$NOHIGH etc.space indicates how large the label widget is to be. A positive value is the absolute length of the widget, whereas value $<$= 0 specifies how far the widget is to be from the righthand edge of the screen. row specifies where to place the widget (as described above). The r





eturned value is the widget identifier for later use.

\par\noindent
\ind{0.5in}
WIDGET mktglwidget (message, number, tgl, tglch, row)
\nwl
char message[];
\nwl
int  number;
\nwl
char tgl[10][20];
\nwl
char tglch;
\nwl
int  row;
\ind{0.0em}
\par\noindent
Creates a new toggle widget. message contains a label for the widget, and number holds the number of toggle values. tgl is used for holding actual toggle values which are toggled between using the activation character tglch. At present there is a limit of 10 toggle values, each being a maximum length of 20 characters. row specifies where to place the widget (as described above). The returned value is the widget identifier for later use.
\par\noindent
}
\newpage
{\nobreak
\ind{0.5in}
WIDGET mkinpwidget (message, character, input, lengthstr, lengthwid, row, exec)
\nwl
char message[], character, input[];
\nwl
int  lengthstr, lengthwid, row, exec; 
\ind{0.0em}
\par\noindent
Creates a new input widget. message contains the label for the widget, and character is the activation character for the widget. input is the variable in which the user wishes the data obtained from the input widget to be placed, lengthstr is the length of input. lengthwid specifies how big to make the widget. A positive value indicates the absolute length of the widget, where as a value $<$= 0 indicates how far from the righthand edge the widget is to be. exec is used to indicate whether the widget should b





e activated on creation by (passing EXEC), or should remain dormant until the activation character is used (passing NOEXEC). (n.b when passing EXEC an activation character is not needed therefore one could pass NULL for character.)

\shead{Text Window Management}
\par\noindent
\nwl

\ind{0.5in}
int opentextwindow (position, border)
\nwl
int position, border;
\ind{0.0em}
\par\noindent
Opens and displays the text window. position specifies where the window is to go. i.e position = 0 will place the window immediately below the lowest widget, position = 1 will allow room for 1 more row of widgets below the current lowest before placing the window etc. border is used to indicate whether the window should be bordered. i.e using the parameters VERTICAL \& HORIZONTAL, one can specify whether the window should be bordered vertically (passing VERTICAL), horizontally (passing HORIZONTAL), both (pa





ssing VERTICAL$|$HORIZONTAL), or neither (passing 0). The function returns the number of lines within the window.

\ind{0.5in}
report (message)
\nwl
char *message;
\ind{0.0em}
\par\noindent
Displays the given message in the text window. Scrolling is done automatically when the bottom of the window is reached and is therefore of no concern for the user.

\ind{0.5in}
cleartextwindow ()
\ind{0.0em}
\par\noindent
Clears the text window and returns its cursor to the top lefthand corner. 

\ind{0.5in}
killtextwindow ()
\ind{0.0em}
\par\noindent
Destroys the text window. The text window can be redefined at a later date.

\shead{Killing Widgets}

\par\noindent
\nwl
\ind{0.5in}
int killwidget (ptr)
\nwl
WIDGET ptr;
\ind{0.0em}
\par\noindent
Kills the given widget. the function returns TRUE if successfull or FALSE if the widget doesn't exist.
}
\newpage
{\nobreak
\shead{Interaction}

\par\noindent
\nwl
\ind{0.5in}
WIDGET widgetinput ()
\ind{0.0em}
\par\noindent
Wait for input from widgets. Program control is passed back when :-
\nwl
a) A Command widget is activated and control is passed to its associated function.
\nwl
b) An input widget is activated and after subsequent input, control is passed to the calling function with the widget pointer of the activated input widget.
\nwl
Activating a toggle widget just toggles the widget, control is only passed back upon one of the above conditions.

\par\noindent
\nwl
\ind{0.5in}
int tsttglwidget (ptr)
\nwl
WIDGET ptr;
\ind{0.0em}
\par\noindent
Returns the index value of the current state of the given toggle widget (0 $<$ index $<$ number toggle values - 1). Returns FALSE if the given widget does not exist.

\par\noindent
\nwl
\ind{0.5in}
int activate (ptr)
\nwl
WIDGET ptr;
\ind{0.0em}
\par\noindent
Reactivates a widget which was previously deactivated. Returns TRUE if successful otherwise FALSE.

\par\noindent
\nwl
\ind{0.5in}
int deactivate (ptr, blank)
\nwl
WIDGET ptr;
\nwl
int    blank;
\ind{0.0em}
\par\noindent
Deactivates the given active widget. The widget remains on screen but it cannot be activated. blank can be BLANK or NOBLANK which indicates whether the contents of the widget should be blanked out or not while it is inactive. The function returns TRUE if successful or FALSE if the given widget does not exist.

\par\noindent
\nwl
\ind{0.5in}
int highlight (ptr)
\nwl
WIDGET ptr;
\ind{0.0em}
\par\noindent
Highlights the given widget. Returns TRUE if successful else FALSE if the widget does not exist.

\par\noindent
\nwl
\ind{0.5in}
int dehighlight (ptr)
\nwl
WIDGET ptr;
\ind{0.0em}
\par\noindent
Turns off the highlighting of the given widget. Returns TRUE if successful else FALSE if the widget does not exist.

\par\noindent
\nwl
\ind{0.5in}
int changelblwidget (ptr, message, position)
\nwl
WIDGET ptr;
\nwl
char   message[];
\nwl
int    position;
\ind{0.0em}
\par\noindent
Changes the contents of the given label widget to that given in message. position specifies how the message is to appear (see mklblwidget). The function returns TRUE if successful else FALSE.
}
{\nobreak
\par\noindent
\nwl
\ind{0.5in}
WIDGETTYPE widgettype (ptr)
\nwl
WIDGET ptr;
\ind{0.0em}
\par\noindent
Returns the type of widget pointed too by ptr. The returned type value is one of CMD, LBL, TGL, INP or FALSE if the widget does not exist.

\shead{Finishing Up}

\par\noindent
\nwl
\ind{0.5in}
endwidgets ()
\ind{0.0em}
\par\noindent
Closes down the windowing system and should be used at the end. This function is also automatically called on an interrupt (e.g \^{}C).
}
%
% end of input file: widget.ms
%--------------------------------------------------
\end{document}
